Skip to content

docs(site): fill out guide and reference pages from README#21

Merged
joelshejar merged 1 commit into
mainfrom
docs/migrate-readme-content
May 11, 2026
Merged

docs(site): fill out guide and reference pages from README#21
joelshejar merged 1 commit into
mainfrom
docs/migrate-readme-content

Conversation

@joelshejar
Copy link
Copy Markdown
Member

Summary

Step 3 in the docs-site work. Replaces the placeholder stubs from PR #20 with real content. ~950 lines of documentation across six pages.

The README is untouched in this PR — it gets trimmed in the next PR once the docs site is live and we can link out to it.

What got filled

Guide

  • getting-started — install, deploy-the-worker-bundle with code-group for Vite/Next/Webpack, construct/start walkthrough, send/receive, two-tab verification, React quickstart, troubleshooting
  • architecture — primary-mode diagram, fallback strategy ladder, outbox semantics, SW handoff explainer, inbound flow, identity, boundary section, ADR cross-links
  • gotchas — six full sections plus a bonus, each with the why + the fix pattern + cross-links to the PRs that surfaced them
  • react — provider setup, both hooks in depth, status shape table, common patterns (connection badge, remote-only handling, logout)

Reference

  • config — required, transport, worker, persistence, SW, leader, per-event option sections. Defaults inline. Cross-refs to gotchas. Full example at the bottom.
  • system-events — per-event documentation for all 8 system events with payload shapes and emission rules. meta field reference. Wildcard subscription pattern.

Test plan

  • `pnpm docs:build` — clean, every internal link resolves
  • `pnpm exec biome check .` — clean
  • Sidebar navigation across guide/, reference/, recipes/, adr/ all work

Follow-ups (not in this PR)

  • Trim the README to ~80 lines and point at the docs site (step 4)
  • Wire the playground iframe to the actual playground build (step 6, needs Vercel deploy config)
  • Configure Vercel (step 7)

Migrates the README's depth content into the VitePress site,
expanding each page to be useful as standalone documentation.
Stubs replaced with real content; the README becomes the source
of truth for the short version (to be trimmed in a follow-up PR
that closes the loop).

Pages filled:

- guide/getting-started — install, deploy-the-worker-bundle (with
  code-group for Vite/Next/Webpack), construct + start walkthrough,
  send/receive, two-tab verification, React quickstart, troubleshooting
- guide/architecture — primary mode diagram, fallback mode strategy
  ladder, outbox semantics, Service Worker handoff, inbound flow,
  identity, boundary section, cross-links to ADRs
- guide/gotchas — six full sections (worker name caching, delivered-
  semantics, no-replay-buffer, browser-only, mobile coverage, SW
  delivery URL) plus a bonus "drain doesn't re-fan-out on reconnect"
  section. PR cross-links for backstory
- guide/react — provider setup, useTabMesh and useTabMeshEvent in
  depth, status shape table, common patterns (connection badge,
  remote-only handling, logout)
- reference/config — required + transport + worker + persistence +
  SW + leader + per-event option sections; defaults inline; cross-
  references to gotchas where applicable; full example at the bottom
- reference/system-events — per-event documentation: hub.connected,
  hub.disconnected, transport.* (4), event.delivery.failed,
  storage.degraded; meta-field reference; wildcard subscription pattern

Verified: `pnpm docs:build` clean, biome clean. README is unchanged
in this commit — it gets trimmed in the next PR once the docs site
is live and we can link to it from the README.
@joelshejar joelshejar merged commit c5bf145 into main May 11, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant